<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.6" />
<title>utstring: dynamic string macros for C</title>
<link rel="stylesheet" href="./tdh.css" type="text/css" />
<script type="text/javascript" src="./asciidoc.js"></script>
<script type="text/javascript" src="./tdh.js"></script>
<script type="text/javascript">
/*<![CDATA[*/
asciidoc.install();
/*]]>*/
</script>
</head>
<body class="article">
<div id="header">
<h1>utstring: dynamic string macros for C</h1>
<span id="author">Troy D. Hanson</span><br />
<span id="email"><tt>&lt;<a href="mailto:thanson@users.sourceforge.net">thanson@users.sourceforge.net</a>&gt;</tt></span><br />
<span id="revnumber">version 1.9.5,</span>
<span id="revdate">November 2011</span>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<a style="float: right; padding-right: 50px" href="http://sourceforge.net/projects/uthash"><img style="border: 0" src="http://sflogo.sourceforge.net/sflogo.php?group_id=163879&amp;type=13" width="120" height="30" alt="uthash at SourceForge.net" /></a>
  <div id="topnav" style="font-size: 9pt; font-family: sans-serif;">
  <a style="padding: 8px;" href="index.html">uthash home</a>
  >>  utstring macros
  </div>
</div>
</div>
<div class="sect1">
<h2 id="_introduction">Introduction</h2>
<div class="sectionbody">
<div id="toc"></div>
<script>
window.onload=generate_TOC

/* Author: Mihai Bazon, September 2002
 * <a href="http://students.infoiasi.ro/~mishoo">http://students.infoiasi.ro/~mishoo</a>
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */

function H_getText(el) {
  var text = "";
  for (var i = el.firstChild; i != null; i = i.nextSibling) {
    if (i.nodeType == 3 /* Node.TEXT_NODE, IE doesn't speak constants */)
      text += i.data;
    else if (i.firstChild != null)
      text += H_getText(i);
  }
  return text;
}

function TOC_EL(el, text, level) {
  this.element = el;
  this.text = text;
  this.level = level;
}

function getHeadlines(el) {
  var l = new Array;
  var rx = /[hH]([2-3])/;
  // internal recursive function that scans the DOM tree
  var rec = function (el) {
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
        if (rx.exec(i.tagName))
          l[l.length] = new TOC_EL(i, H_getText(i), parseInt(RegExp.$1));
        rec(i);
      }
    }
  }
  rec(el);
  return l;
}

function generate_TOC() {
  var parent = document.getElementById("toc");
  var toc_hdr = document.createElement("div");
  var toc_hdr_txt = document.createTextNode("CONTENTS");
  toc_hdr.appendChild(toc_hdr_txt);
  /* toc_hdr.setAttribute("id","hdr"); */
  toc_hdr.id = "hdr";
  parent.appendChild(toc_hdr);
  var hs = getHeadlines(document.getElementsByTagName("body")[0]);
  for (var i = 0; i < hs.length; ++i) {
    var hi = hs[i];
    var d = document.createElement("div");
    if (hi.element.id == "") hi.element.id = "gen" + i;
    var a = document.createElement("a");
    a.href = "#" + hi.element.id;
    a.appendChild(document.createTextNode(hi.text));
    d.appendChild(a);
    d.className = "level" + hi.level;
    parent.appendChild(d);
    /*
    if (hi.level == 3) {
        var dvtop = document.createElement("div");
        dvtop.className = "toplink";
        dvtop.appendChild(document.createTextNode("^top^"));
        dvtop.onclick=function(){scrollTo(0,0);};
        hi.element.appendChild(dvtop);
    }
    */
  }
}
</script>
<div class="paragraph"><p>A set of very basic dynamic string macros for C programs are included with
uthash in <tt>utstring.h</tt>.  To use these macros in your own C program, just
copy <tt>utstring.h</tt> into your source directory and use it in your programs.</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>#include "utstring.h"</tt></pre>
</div></div>
<div class="paragraph"><p>The dynamic string supports basic operations such as inserting data (including
binary data-- despite its name, utstring is not limited to string content),
concatenation, getting the length and content, and clearing it.  The string
<a href="#operations">operations</a> are listed below.</p></div>
<div class="sect2">
<h3 id="_download">Download</h3>
<div class="paragraph"><p>To download the <tt>utstring.h</tt> header file, follow the link on the
<a href="http://uthash.sourceforge.net">uthash home page</a>.</p></div>
</div>
<div class="sect2">
<h3 id="_bsd_licensed">BSD licensed</h3>
<div class="paragraph"><p>This software is made available under the
<a href="license.html">revised BSD license</a>.
It is free and open source.</p></div>
</div>
<div class="sect2">
<h3 id="_platforms">Platforms</h3>
<div class="paragraph"><p>The <em>utstring</em> macros have been tested on:</p></div>
<div class="ulist"><ul>
<li>
<p>
Linux,
</p>
</li>
<li>
<p>
Windows, using Visual Studio 2008 and Visual Studio 2010
</p>
</li>
</ul></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_usage">Usage</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_declaration">Declaration</h3>
<div class="paragraph"><p>The dynamic string itself has the data type <tt>UT_string</tt>.  It is declared like,</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>UT_string *str;</tt></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_new_and_free">New and free</h3>
<div class="paragraph"><p>The next step is to create the string using <tt>utstring_new</tt>. Later when you&#8217;re
done with it, <tt>utstring_free</tt> will free it and all its content.</p></div>
</div>
<div class="sect2">
<h3 id="_manipulation">Manipulation</h3>
<div class="paragraph"><p>The <tt>utstring_printf</tt> or <tt>utstring_bincpy</tt> operations insert (copy) data into
the string. To concatenate one utstring to another, use <tt>utstring_concat</tt>.  To
clear the content of the string, use <tt>utstring_clear</tt>. The length of the string
is available from <tt>utstring_len</tt>, and its content from <tt>utstring_body</tt>. This
evaluates to a <tt>char*</tt>.  The buffer it points to is always null-terminated.
So, it can be used directly with external functions that expect a string.
This automatic null terminator is not counted in the length of the string.</p></div>
</div>
<div class="sect2">
<h3 id="_samples">Samples</h3>
<div class="paragraph"><p>These examples show how to use utstring.</p></div>
<div class="listingblock">
<div class="title">Sample 1</div>
<div class="content">
<pre><tt>#include &lt;stdio.h&gt;
#include "utstring.h"

int main() {
    UT_string *s;

    utstring_new(s);
    utstring_printf(s, "hello world!" );
    printf("%s\n", utstring_body(s));

    utstring_free(s);
    return 0;
}</tt></pre>
</div></div>
<div class="paragraph"><p>The next example is meant to demonstrate that printf <em>appends</em> to the string.
It also shows concatenation.</p></div>
<div class="listingblock">
<div class="title">Sample 2</div>
<div class="content">
<pre><tt>#include &lt;stdio.h&gt;
#include "utstring.h"

int main() {
    UT_string *s, *t;

    utstring_new(s);
    utstring_new(t);

    utstring_printf(s, "hello " );
    utstring_printf(s, "world " );

    utstring_printf(t, "hi " );
    utstring_printf(t, "there " );

    utstring_concat(s, t);
    printf("length: %u\n", utstring_len(s));
    printf("%s\n", utstring_body(s));

    utstring_free(s);
    utstring_free(t);
    return 0;
}</tt></pre>
</div></div>
<div class="paragraph"><p>The last example shows how binary data can be inserted into the string. It also
clears the string and prints new data into it.</p></div>
<div class="listingblock">
<div class="title">Sample 3</div>
<div class="content">
<pre><tt>#include &lt;stdio.h&gt;
#include "utstring.h"

int main() {
    UT_string *s;
    char binary[] = "\xff\xff";

    utstring_new(s);
    utstring_bincpy(s, binary, sizeof(binary));
    printf("length is %u\n", utstring_len(s));

    utstring_clear(s);
    utstring_printf(s,"number %d", 10);
    printf("%s\n", utstring_body(s));

    utstring_free(s);
    return 0;
}</tt></pre>
</div></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="operations">Reference</h2>
<div class="sectionbody">
<div class="paragraph"><p>These are the utstring operations.</p></div>
<div class="sect2">
<h3 id="_operations">Operations</h3>
<div class="tableblock">
<table rules="none"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="55%" />
<col width="44%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><tt>utstring_new(s)</tt></p></td>
<td align="left" valign="top"><p class="table">allocate a new utstring</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><tt>utstring_renew(s)</tt></p></td>
<td align="left" valign="top"><p class="table">allocate a new utstring (if s is <tt>NULL</tt>) otherwise clears it</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><tt>utstring_free(s)</tt></p></td>
<td align="left" valign="top"><p class="table">free an allocated utstring</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><tt>utstring_init(s)</tt></p></td>
<td align="left" valign="top"><p class="table">init a utstring (non-alloc)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><tt>utstring_done(s)</tt></p></td>
<td align="left" valign="top"><p class="table">dispose of a utstring (non-allocd)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><tt>utstring_printf(s,fmt,&#8230;)</tt></p></td>
<td align="left" valign="top"><p class="table">printf into a utstring (appends)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><tt>utstring_bincpy(s,bin,len)</tt></p></td>
<td align="left" valign="top"><p class="table">insert binary data of length len (appends)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><tt>utstring_concat(dst,src)</tt></p></td>
<td align="left" valign="top"><p class="table">concatenate src utstring to end of dst utstring</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><tt>utstring_clear(s)</tt></p></td>
<td align="left" valign="top"><p class="table">clear the content of s (setting its length to 0)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><tt>utstring_len(s)</tt></p></td>
<td align="left" valign="top"><p class="table">obtain the length of s as an unsigned integer</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><tt>utstring_body(s)</tt></p></td>
<td align="left" valign="top"><p class="table">get <tt>char*</tt> to body of s (buffer is always null-terminated)</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_notes">Notes</h3>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
<tt>utstring_new</tt> and <tt>utstring_free</tt> are used to allocate a new string and free it,
   while <tt>utstring_init</tt> and <tt>utstring_done</tt> can be used if the UT_string is already
   allocated and just needs to be initialized or have its internal resources
   freed.
</p>
</li>
<li>
<p>
<tt>utstring_printf</tt> is actually a function defined statically in <tt>utstring.h</tt>
   rather than a macro.
</p>
</li>
</ol></div>
</div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Version 1.9.5<br />
Last updated 2011-11-16 23:21:49 EST
</div>
</div>
</body>
</html>
